3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Storage Objects

QuickDraw 3D provides several general routines for getting the type and size of storage objects. It also provides routines you can use to get and set the private data of a storage object.

Q3Storage_GetType

You can use the Q3Storage_GetType function to get the type of a storage object.



 
TQ3ObjectType Q3Storage_GetType (TQ3StorageObject storage);

storage: A storage object.

DESCRIPTION

The Q3Storage_GetType function returns, as its function result, the type of the storage object specified by the storage parameter. The types of storage objects currently supported by QuickDraw 3D are defined by these constants:



 
kQ3StorageTypeMemory

kQ3StorageTypeMacintosh

kQ3StorageTypeUnix

kQ3StorageTypeWin32

If the specified storage object is invalid or is not one of these types, Q3Storage_GetType returns the value kQ3ObjectTypeInvalid .

ERRORS

kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter

Q3Storage_GetSize

You can use the Q3Storage_GetSize function to get the size of the data stored in a storage object.



 
TQ3Status Q3Storage_GetSize (

                     TQ3StorageObject storage, 

                     unsigned long *size);

storage: A storage object.
size: On entry, a pointer to a buffer. On exit, the number of bytes of data stored in the specified storage object.

DESCRIPTION

The Q3Storage_GetSize function returns, through the size parameter, the number of bytes of data stored in the storage object specified by the storage parameter. That storage object must already be open when you call Q3Storage_GetSize .

ERRORS

kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter kQ3ErrorStorageNotOpen

Q3Storage_GetData

You can use the Q3Storage_GetData function to get the data stored in a storage object.



 
TQ3Status Q3Storage_GetData (

                     TQ3StorageObject storage, 

                     unsigned long offset, 

                     unsigned long dataSize, 

                     unsigned char *data, 

                     unsigned long *sizeRead);

storage: A storage object.
offset: An offset into the private data associated with the specified storage object.
dataSize: The number of bytes of data from the specified storage object to be returned in the specified buffer.
data: On entry, a pointer to a buffer that is at least large enough to contain the number of bytes of data specified by the dataSize parameter. On exit, this buffer is filled with data from the specified storage object.
sizeRead: On exit, the number of bytes of data read from the specified storage object.

DESCRIPTION

The Q3Storage_GetData function returns, through the data parameter, some or all of the private data associated with the storage object specified by the storage parameter. The data to be returned begins at an offset specified by the offset parameter and extends for dataSize bytes from that location. On exit, the sizeRead parameter contains the number of bytes actually retrieved from the storage object's private data into the data buffer. If the value returned in the sizeRead parameter is less than the number of bytes requested in the dataSize parameter, then the end of the storage object's private data occurs at the distance offset + sizeRead from the beginning of the private data.

If the specified storage object is associated with a file object, that file object must be closed before you call Q3Storage_GetData .

Q3Storage_SetData

You can use the Q3Storage_SetData function to set the data stored in a storage object.



 
TQ3Status Q3Storage_SetData (

                     TQ3StorageObject storage, 

                     unsigned long offset, 

                     unsigned long dataSize, 

                     const unsigned char *data, 

                     unsigned long *sizeWritten);

storage: A storage object.
offset: An offset into the specified storage object.
dataSize: The number of bytes of data from the specified buffer to be written to the specified storage object.
data: On entry, a pointer to a buffer that contains the data you want to be written to the specified storage object.
sizeWritten: On exit, the number of bytes of data written to the specified storage object.

DESCRIPTION

The Q3Storage_SetData function sets the data associated with the storage object specified by the storage parameter to the data specified by the dataSize and data parameters. The data is written to the storage object starting at the byte offset specified by the offset parameter. Q3Storage_SetData returns, in the sizeWritten parameter, the number of bytes of data written to the storage object. If the value returned in the sizeWritten parameter is less than the number of bytes requested in the dataSize parameter, then the end of the storage object's private data occurs at the distance offset + sizeWritten from the beginning of the private data.